home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / artsc / artsc.h < prev   
Encoding:
C/C++ Source or Header  |  2005-09-10  |  8.1 KB  |  247 lines
  1.     /*
  2.  
  3.     Copyright (C) 2000 Stefan Westerfeld
  4.                        stefan@space.twc.de
  5.  
  6.     This library is free software; you can redistribute it and/or
  7.     modify it under the terms of the GNU Library General Public
  8.     License as published by the Free Software Foundation; either
  9.     version 2 of the License, or (at your option) any later version.
  10.   
  11.     This library is distributed in the hope that it will be useful,
  12.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.     Library General Public License for more details.
  15.  
  16.     You should have received a copy of the GNU Library General Public License
  17.     along with this library; see the file COPYING.LIB.  If not, write to
  18.     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19.     Boston, MA 02111-1307, USA.
  20.  
  21.     */
  22.  
  23. #ifndef ARTSC_H
  24. #define ARTSC_H
  25.  
  26. #include "artsc_export.h"
  27.  
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif
  31.  
  32. /**
  33.  * @libdoc aRts plain C API
  34.  *
  35.  * The aRts plain C API aims at easily writing/porting plain C apps to the
  36.  * arts sound server. What is provided is streaming functionality, in a
  37.  * blocking way. So for most apps, you simply remove the few system calls
  38.  * that deal with your audio device, and replace them with the appropriate
  39.  * arts calls.
  40.  */
  41.  
  42. /**
  43.  * the type of streams (simply treat these as black boxes)
  44.  */
  45. typedef void *arts_stream_t;
  46.  
  47. /* error codes */
  48.  
  49. #define ARTS_E_NOSERVER     ( -1 )
  50. #define ARTS_E_NOBACKEND    ( -2 )
  51. #define ARTS_E_NOSTREAM     ( -3 )
  52. #define ARTS_E_NOINIT       ( -4 )
  53. #define ARTS_E_NOIMPL       ( -5 )
  54.  
  55. /**
  56.  * the values for stream parameters
  57.  *
  58.  * @see arts_parameter_t
  59.  */
  60. enum arts_parameter_t_enum {
  61.     ARTS_P_BUFFER_SIZE = 1,
  62.     ARTS_P_BUFFER_TIME = 2,
  63.     ARTS_P_BUFFER_SPACE = 3,
  64.     ARTS_P_SERVER_LATENCY = 4,
  65.     ARTS_P_TOTAL_LATENCY = 5,
  66.     ARTS_P_BLOCKING = 6,
  67.     ARTS_P_PACKET_SIZE = 7,
  68.     ARTS_P_PACKET_COUNT = 8,
  69.     ARTS_P_PACKET_SETTINGS = 9
  70. };
  71.  
  72. /**
  73.  * parameters for streams
  74.  *
  75.  * @li ARTS_P_BUFFER_SIZE (rw)
  76.  *   The size of the internal buffers used for streaming to the server - this
  77.  *   directly affects the latency that will occur. If you never set it
  78.  *   explicitly, this value defaults to at least 65536 (64kb). Generally,
  79.  *   it is important to know that the server itself gives some constraints
  80.  *   which makes buffer sizes below a certain value impossible. So setting
  81.  *   this parameter will always result in either getting what you wanted,
  82.  *   or a larger streaming buffer due to server limitations.
  83.  *
  84.  * @li ARTS_P_BUFFER_TIME (rw)
  85.  *   The time the buffer used for streaming to the server takes to play in
  86.  *   milliseconds. This is just a more human readable method to set the buffer
  87.  *   size, so setting ARTS_P_BUFFER_SIZE affects this parameter and the other
  88.  *   way round. As aRts chooses reasonable buffer sizes for streaming (rather
  89.  *   3*16kb than 40234 bytes), setting this parameter will often end up with
  90.  *   a slightly larger value than you requested.
  91.  *
  92.  * @li ARTS_P_BUFFER_SPACE (r)
  93.  *   The amount of bytes that can be read/written without blocking (depending
  94.  *   whether this is a record or play stream). As requesting this parameter
  95.  *   does a few system calls (but no remote invocation) to verify that it is
  96.  *   up-to-date, don't overuse it.
  97.  *
  98.  * @li ARTS_P_SERVER_LATENCY (r)
  99.  *   The amount of latency the server creates (due to hardware buffering)
  100.  *   in milliseconds.
  101.  *
  102.  * @li ARTS_P_TOTAL_LATENCY (r)
  103.  *   The overall latency in milliseconds it takes (at most), from the time
  104.  *   when you write a byte into a stream, until it gets played on the
  105.  *   soundcard. This is simply a shortcut to the sum of ARTS_P_BUFFER_TIME
  106.  *   and ARTS_P_SERVER_LATENCY.
  107.  *
  108.  * @li ARTS_P_BLOCKING (rw)
  109.  *   If this parameter is 1 (the default), arts_read/arts_write will block
  110.  *   when not all data can be read/written successfully, and wait until it
  111.  *   works. If this parameter is 0, arts_read/arts_write will return
  112.  *   the number of successfully read/written bytes immediately.
  113.  *
  114.  * @li ARTS_P_PACKET_SIZE (r)
  115.  *   This returns the size of the packets used for buffering. The optimal
  116.  *   size for arts_stream_write is always writing one packet. The buffering of
  117.  *   streams works with audio packets. So the ARTS_P_BUFFER_SIZE parameter of
  118.  *   streams (which specifies how many bytes of a stream are prebuffered),
  119.  *   really consists of (ARTS_P_PACKET_SIZE) * (ARTS_P_PACKET_COUNT).
  120.  *
  121.  * @li ARTS_P_PACKET_COUNT (r)
  122.  *   This returns the number of the packets are used for buffering. See
  123.  *   ARTS_P_PACKET_SIZE for more.
  124.  *
  125.  * @li ARTS_P_PACKET_SETTINGS (rw)
  126.  *   This is a way to configure packet size & packet count at the same time.
  127.  *   The format is 0xCCCCSSSS, where 2^SSSS is the packet size, and CCCC is
  128.  *   the packet count. Note that when writing this, you don't necessarily
  129.  *   get the settings you requested.
  130.  */
  131. typedef enum arts_parameter_t_enum arts_parameter_t;
  132.  
  133. /**
  134.  * initializes the aRts C API, and connects to the sound server
  135.  *
  136.  * @return 0 if everything is all right, an error code otherwise
  137.  */
  138.  
  139. ARTSC_EXPORT int arts_init(void);
  140.  
  141. /**
  142.  * disconnects from the sound server and frees the aRts C API internals
  143.  */
  144. ARTSC_EXPORT void arts_free(void);
  145.  
  146. /**
  147.  * asks aRtsd to free the DSP device and return 1 if it was successful,
  148.  * 0 if there were active non-suspendable modules
  149.  */
  150. ARTSC_EXPORT int arts_suspend(void);
  151.  
  152. /**
  153.  * asks aRtsd if the DSP device is free and return 1 if it is,
  154.  * 0 if not
  155.  */
  156. ARTSC_EXPORT int arts_suspended(void);
  157.  
  158.  
  159. /**
  160.  * converts an error code to a human readable error message
  161.  *
  162.  * @param errorcode the errorcode (from another arts function that failed)
  163.  * @returns a text string with the error message
  164.  */
  165. ARTSC_EXPORT const char *arts_error_text(int errorcode);
  166.  
  167. /**
  168.  * open a stream for playing
  169.  *
  170.  * @param rate the sampling rate (something like 44100)
  171.  * @param bits how many bits each sample has (8 or 16)
  172.  * @param channels how many channels, 1 is mono, 2 is stereo
  173.  * @param name the name of the stream (these will be used so that the user can
  174.  *          assign streams to effects/mixer channels and similar)
  175.  *
  176.  * @return a stream
  177.  */
  178. ARTSC_EXPORT arts_stream_t arts_play_stream(int rate, int bits, int channels, const char *name);
  179.  
  180. /**
  181.  * open a stream for recording
  182.  *
  183.  * @param rate the sampling rate (something like 44100)
  184.  * @param bits how many bits each sample has (8 or 16)
  185.  * @param channels how many channels, 1 is mono, 2 is stereo
  186.  * @param name the name of the stream (these will be used so that the user can
  187.  *          assign streams to effects/mixer channels and similar)
  188.  *
  189.  * @return a stream
  190.  */
  191. ARTSC_EXPORT arts_stream_t arts_record_stream(int rate, int bits, int channels, const char *name);
  192.  
  193. /**
  194.  * close a stream
  195.  */
  196. ARTSC_EXPORT void arts_close_stream(arts_stream_t stream);
  197.  
  198. /**
  199.  * read samples from stream
  200.  *
  201.  * @param stream a previously opened record stream
  202.  * @param buffer a buffer with sample data
  203.  * @param count the number of bytes contained in the buffer
  204.  *
  205.  * @returns number of read bytes on success or error code
  206.  */
  207. ARTSC_EXPORT int arts_read(arts_stream_t stream, void *buffer, int count);
  208.  
  209. /**
  210.  * write samples to to stream
  211.  *
  212.  * @param stream a previously opened play stream
  213.  * @param buffer a buffer with sample data
  214.  * @param count the number of bytes contained in the buffer
  215.  *
  216.  * @returns number of written bytes on success or error code
  217.  */
  218. ARTSC_EXPORT int arts_write(arts_stream_t stream, const void *buffer, int count);
  219.  
  220. /**
  221.  * configure a parameter of a stream
  222.  *
  223.  * @param stream an opened record or play stream
  224.  * @param parameter the parameter you want to modify
  225.  * @param value the new value
  226.  *
  227.  * @returns the new value of the parameter (which may or may not be the value
  228.  *          you wanted to have), or an error code if something went wrong
  229.  */
  230. ARTSC_EXPORT int arts_stream_set(arts_stream_t stream, arts_parameter_t param, int value);
  231.  
  232. /**
  233.  * query a parameter of a stream
  234.  *
  235.  * @param stream an opened record or play stream
  236.  * @param parameter the parameter you want to query
  237.  *
  238.  * @returns the value of the parameter, or an error code
  239.  */
  240. ARTSC_EXPORT int arts_stream_get(arts_stream_t stream, arts_parameter_t param);
  241.  
  242. #ifdef __cplusplus
  243. }
  244. #endif
  245.  
  246. #endif /* ARTSC_H */
  247.